home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / AIncludes / NameRegistry.a < prev    next >
Encoding:
Text File  |  1998-02-12  |  15.2 KB  |  562 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        NameRegistry.a
  3. ;
  4. ;    Contains:    NameRegistry Interfaces
  5. ;
  6. ;    Version:    Technology:    MacOS
  7. ;                Release:    Universal Interfaces 3.1
  8. ;
  9. ;    Copyright:    © 1993-1998 by Apple Computer, Inc., all rights reserved.
  10. ;
  11. ;    Bugs?:        Please include the the file and version information (from above) with
  12. ;                the problem description.  Developers belonging to one of the Apple
  13. ;                developer programs can submit bug reports to:
  14. ;
  15. ;                    devsupport@apple.com
  16. ;
  17. ;
  18.     IF &TYPE('__NAMEREGISTRY__') = 'UNDEFINED' THEN
  19. __NAMEREGISTRY__ SET 1
  20.  
  21.     IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN
  22.     include 'MacTypes.a'
  23.     ENDIF
  24.  
  25. ; *******************************************************************************
  26. ; * 
  27. ; * Foundation Types
  28. ; *
  29. ; 
  30.  
  31. ;  Value of a property 
  32. ; typedef void *                        RegPropertyValue
  33.  
  34. ;  Length of property value 
  35. ; typedef UInt32                         RegPropertyValueSize
  36.  
  37. ; *******************************************************************************
  38. ; * 
  39. ; * RegEntryID    :    The Global x-Namespace Entry Identifier
  40. ; *
  41. ; 
  42.  
  43. RegEntryID                RECORD 0
  44. contents                 ds.l    4                ; offset: $0 (0)
  45. sizeof                     EQU *                    ; size:   $10 (16)
  46.                         ENDR
  47. ; typedef struct RegEntryID *            RegEntryIDPtr
  48.  
  49. ; *******************************************************************************
  50. ; *
  51. ; * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  52. ; *
  53. ; *    • Names are a colon-separated list of name components.  Name components
  54. ; *      may not themselves contain colons.  
  55. ; *    • Names are presented as null-terminated ASCII character strings.
  56. ; *    • Names follow similar parsing rules to Apple file system absolute
  57. ; *      and relative paths.  However the '::' parent directory syntax is
  58. ; *      not currently supported.
  59. ; 
  60.  
  61. ;  Max length of Entry Name 
  62.  
  63. kRegCStrMaxEntryNameLength        EQU        47
  64. ;  Entry Names are single byte ASCII 
  65. ; typedef char                             RegCStrEntryName
  66.  
  67. ; typedef char *                        RegCStrEntryNamePtr
  68.  
  69. ;  length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1
  70. RegCStrEntryNameBuf        RECORD 0
  71. elements                 ds.b    48
  72. sizeof                     EQU *                    ; size:   $30 (48)
  73.                         ENDR
  74.  
  75.  
  76. ; typedef char                             RegCStrPathName
  77.  
  78. ; typedef UInt32                         RegPathNameSize
  79.  
  80.  
  81. kRegPathNameSeparator            EQU        58                    ; 0x3A 
  82. kRegEntryNameTerminator            EQU        $00                    ; '\0' 
  83. kRegPathNameTerminator            EQU        $00                    ; '\0' 
  84. ; *******************************************************************************
  85. ; *
  86. ; * Property Name and ID Definitions
  87. ; *    (Applies to all Properties Regardless of NameSpace)
  88. ; 
  89.  
  90.  
  91. kRegMaximumPropertyNameLength    EQU        31                    ; Max length of Property Name 
  92. kRegPropertyNameTerminator        EQU        $00                    ; '\0' 
  93. RegPropertyNameBuf        RECORD 0
  94. elements                 ds.b    32
  95. sizeof                     EQU *                    ; size:   $20 (32)
  96.                         ENDR
  97.  
  98.  
  99. ; typedef char                             RegPropertyName
  100.  
  101. ; typedef char *                        RegPropertyNamePtr
  102.  
  103. ; *******************************************************************************
  104. ; *
  105. ; * Iteration Operations
  106. ; *
  107. ; *    These specify direction when traversing the name relationships
  108. ; 
  109.  
  110. ; typedef UInt32                         RegIterationOp
  111.  
  112. ; typedef RegIterationOp                 RegEntryIterationOp
  113.  
  114.  
  115.                                                             ; Absolute locations
  116. kRegIterRoot                    EQU        $00000002            ; "Upward" Relationships    
  117. kRegIterParents                    EQU        $00000003            ; include all  parent(s) of entry 
  118.                                                             ; "Downward" Relationships
  119. kRegIterChildren                EQU        $00000004            ; include all children 
  120. kRegIterSubTrees                EQU        $00000005            ; include all sub trees of entry 
  121. kRegIterDescendants                EQU        $00000005            ; include all descendants of entry 
  122.                                                             ; "Horizontal" Relationships    
  123. kRegIterSibling                    EQU        $00000006            ; include all siblings 
  124.                                                             ; Keep doing the same thing
  125. kRegIterContinue                EQU        $00000001
  126. ; *******************************************************************************
  127. ; *
  128. ; * Name Entry and Property Modifiers
  129. ; *
  130. ; *
  131. ; *
  132. ; * Modifiers describe special characteristics of names
  133. ; * and properties.  Modifiers might be supported for
  134. ; * some names and not others.
  135. ; * 
  136. ; * Device Drivers should not rely on functionality
  137. ; * specified as a modifier.
  138. ; 
  139.  
  140. ; typedef UInt32                         RegModifiers
  141.  
  142. ; typedef RegModifiers                     RegEntryModifiers
  143.  
  144. ; typedef RegModifiers                     RegPropertyModifiers
  145.  
  146.  
  147. kRegNoModifiers                    EQU        $00000000            ; no entry modifiers in place 
  148. kRegUniversalModifierMask        EQU        $0000FFFF            ; mods to all entries 
  149. kRegNameSpaceModifierMask        EQU        $00FF0000            ; mods to all entries within namespace 
  150. kRegModifierMask                EQU        $FF000000            ; mods to just this entry 
  151. ;  Universal Property Modifiers 
  152.  
  153. kRegPropertyValueIsSavedToNVRAM    EQU        $00000020            ; property is non-volatile (saved in NVRAM) 
  154. kRegPropertyValueIsSavedToDisk    EQU        $00000040            ; property is non-volatile (saved on disk) 
  155. ;  ///////////////////////
  156. ;//
  157. ;// The Registry API
  158. ;//
  159. ;/////////////////////// 
  160.  
  161. ;  ///////////////////////
  162. ;//
  163. ;// Entry Management
  164. ;//
  165. ;/////////////////////// 
  166.  
  167.  
  168. ; -------------------------------
  169. ; * EntryID handling
  170. ; 
  171.  
  172. ; 
  173. ; * Initialize an EntryID to a known invalid state
  174. ; *   note: invalid != uninitialized
  175. ; 
  176.  
  177. ;
  178. ; extern OSStatus RegistryEntryIDInit(RegEntryID *id)
  179. ;
  180.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  181.         IMPORT_CFM_FUNCTION RegistryEntryIDInit
  182.     ENDIF
  183.  
  184. ; 
  185. ; * Compare EntryID's for equality or if invalid
  186. ; *
  187. ; * If a NULL value is given for either id1 or id2, the other id 
  188. ; * is compared with an invalid ID.  If both are NULL, the id's 
  189. ; * are consided equal (result = true). 
  190. ; 
  191.  
  192. ;
  193. ; extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2)
  194. ;
  195.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  196.         IMPORT_CFM_FUNCTION RegistryEntryIDCompare
  197.     ENDIF
  198.  
  199. ; 
  200. ; * Copy an EntryID
  201. ; 
  202.  
  203. ;
  204. ; extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst)
  205. ;
  206.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  207.         IMPORT_CFM_FUNCTION RegistryEntryIDCopy
  208.     ENDIF
  209.  
  210. ; 
  211. ; * Free an ID so it can be reused.
  212. ; 
  213.  
  214. ;
  215. ; extern OSStatus RegistryEntryIDDispose(RegEntryID *id)
  216. ;
  217.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  218.         IMPORT_CFM_FUNCTION RegistryEntryIDDispose
  219.     ENDIF
  220.  
  221. ; -------------------------------
  222. ; * Adding and removing entries
  223. ; *
  224. ; * If (parentEntry) is NULL, the name is assumed
  225. ; * to be a rooted path. It is rooted to an anonymous, unnamed root.
  226. ; 
  227.  
  228. ;
  229. ; extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry)
  230. ;
  231.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  232.         IMPORT_CFM_FUNCTION RegistryCStrEntryCreate
  233.     ENDIF
  234.  
  235. ;
  236. ; extern OSStatus RegistryEntryDelete(const RegEntryID *id)
  237. ;
  238.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  239.         IMPORT_CFM_FUNCTION RegistryEntryDelete
  240.     ENDIF
  241.  
  242. ;
  243. ; extern OSStatus RegistryEntryCopy(RegEntryID *parentEntryID, RegEntryID *sourceDevice, RegEntryID *destDevice)
  244. ;
  245.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  246.         IMPORT_CFM_FUNCTION RegistryEntryCopy
  247.     ENDIF
  248.  
  249. ; ---------------------------
  250. ; * Traversing the namespace
  251. ; *
  252. ; * To support arbitrary namespace implementations in the future,
  253. ; * I have hidden the form that the place pointer takes.  The previous
  254. ; * interface exposed the place pointer by specifying it as a
  255. ; * RegEntryID.
  256. ; *
  257. ; * I have also removed any notion of returning the entries
  258. ; * in a particular order, because an implementation might
  259. ; * return the names in semi-random order.  Many name service
  260. ; * implementations will store the names in a hashed lookup
  261. ; * table.
  262. ; *
  263. ; * Writing code to traverse some set of names consists of
  264. ; * a call to begin the iteration, the iteration loop, and
  265. ; * a call to end the iteration.  The begin call initializes
  266. ; * the iteration cookie data structure.  The call to end the 
  267. ; * iteration should be called even in the case of error so 
  268. ; * that allocated data structures can be freed.
  269. ; *
  270. ; *    Create(...)
  271. ; *    do {
  272. ; *        Iterate(...);
  273. ; *    } while (!done);
  274. ; *    Dispose(...);
  275. ; *
  276. ; * This is the basic code structure for callers of the iteration
  277. ; * interface.
  278. ; 
  279.  
  280.  
  281.  
  282. ;  
  283. ; * create/dispose the iterator structure
  284. ; *   defaults to root with relationship = kRegIterDescendants
  285. ; 
  286.  
  287. ;
  288. ; extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie)
  289. ;
  290.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  291.         IMPORT_CFM_FUNCTION RegistryEntryIterateCreate
  292.     ENDIF
  293.  
  294. ;
  295. ; extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie)
  296. ;
  297.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  298.         IMPORT_CFM_FUNCTION RegistryEntryIterateDispose
  299.     ENDIF
  300.  
  301. ;  
  302. ; * set Entry Iterator to specified entry
  303. ; 
  304.  
  305. ;
  306. ; extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID)
  307. ;
  308.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  309.         IMPORT_CFM_FUNCTION RegistryEntryIterateSet
  310.     ENDIF
  311.  
  312. ; 
  313. ; * Return each value of the iteration
  314. ; *
  315. ; * return entries related to the current entry
  316. ; * with the specified relationship
  317. ; 
  318.  
  319. ;
  320. ; extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done)
  321. ;
  322.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  323.         IMPORT_CFM_FUNCTION RegistryEntryIterate
  324.     ENDIF
  325.  
  326. ; 
  327. ; * return entries with the specified property
  328. ; *
  329. ; * A NULL RegPropertyValue pointer will return an
  330. ; * entry with the property containing any value.
  331. ; 
  332.  
  333. ;
  334. ; extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  335. ;
  336.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  337.         IMPORT_CFM_FUNCTION RegistryEntrySearch
  338.     ENDIF
  339.  
  340. ; --------------------------------
  341. ; * Find a name in the namespace
  342. ; *
  343. ; * This is the fast lookup mechanism.
  344. ; * NOTE:  A reverse lookup mechanism
  345. ; *      has not been provided because
  346. ; *        some name services may not
  347. ; *        provide a fast, general reverse
  348. ; *        lookup.
  349. ; 
  350.  
  351. ;
  352. ; extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry)
  353. ;
  354.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  355.         IMPORT_CFM_FUNCTION RegistryCStrEntryLookup
  356.     ENDIF
  357.  
  358. ; ---------------------------------------------
  359. ; * Convert an entry to a rooted name string
  360. ; *
  361. ; * A utility routine to turn an Entry ID
  362. ; * back into a name string.
  363. ; 
  364.  
  365. ;
  366. ; extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize)
  367. ;
  368.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  369.         IMPORT_CFM_FUNCTION RegistryEntryToPathSize
  370.     ENDIF
  371.  
  372. ;
  373. ; extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize)
  374. ;
  375.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  376.         IMPORT_CFM_FUNCTION RegistryCStrEntryToPath
  377.     ENDIF
  378.  
  379. ; 
  380. ; * Parse a path name.
  381. ; *
  382. ; * Retrieve the last component of the path, and
  383. ; * return a spec for the parent.
  384. ; 
  385.  
  386. ;
  387. ; extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done)
  388. ;
  389.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  390.         IMPORT_CFM_FUNCTION RegistryCStrEntryToName
  391.     ENDIF
  392.  
  393. ;  //////////////////////////////////////////////////////
  394. ;//
  395. ;// Property Management
  396. ;//
  397. ;////////////////////////////////////////////////////// 
  398.  
  399. ; -------------------------------
  400. ; * Adding and removing properties
  401. ; 
  402.  
  403. ;
  404. ; extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  405. ;
  406.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  407.         IMPORT_CFM_FUNCTION RegistryPropertyCreate
  408.     ENDIF
  409.  
  410. ;
  411. ; extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName)
  412. ;
  413.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  414.         IMPORT_CFM_FUNCTION RegistryPropertyDelete
  415.     ENDIF
  416.  
  417. ;
  418. ; extern OSStatus RegistryPropertyRename(const RegEntryID *entry, const RegPropertyName *oldName, const RegPropertyName *newName)
  419. ;
  420.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  421.         IMPORT_CFM_FUNCTION RegistryPropertyRename
  422.     ENDIF
  423.  
  424. ; ---------------------------
  425. ; * Traversing the Properties of a name
  426. ; *
  427. ; 
  428.  
  429.  
  430.  
  431. ;
  432. ; extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie)
  433. ;
  434.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  435.         IMPORT_CFM_FUNCTION RegistryPropertyIterateCreate
  436.     ENDIF
  437.  
  438. ;
  439. ; extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie)
  440. ;
  441.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  442.         IMPORT_CFM_FUNCTION RegistryPropertyIterateDispose
  443.     ENDIF
  444.  
  445. ;
  446. ; extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done)
  447. ;
  448.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  449.         IMPORT_CFM_FUNCTION RegistryPropertyIterate
  450.     ENDIF
  451.  
  452. ; 
  453. ; * Get the value of the specified property for the specified entry.
  454. ; *
  455. ; 
  456.  
  457. ;
  458. ; extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize)
  459. ;
  460.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  461.         IMPORT_CFM_FUNCTION RegistryPropertyGetSize
  462.     ENDIF
  463.  
  464. ; 
  465. ; * (*propertySize) is the maximum size of the value returned in the buffer
  466. ; * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  467. ; * value returned.
  468. ; 
  469.  
  470. ;
  471. ; extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize)
  472. ;
  473.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  474.         IMPORT_CFM_FUNCTION RegistryPropertyGet
  475.     ENDIF
  476.  
  477. ;
  478. ; extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  479. ;
  480.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  481.         IMPORT_CFM_FUNCTION RegistryPropertySet
  482.     ENDIF
  483.  
  484. ;  //////////////////////////////////////////////////////
  485. ;//
  486. ;// Modifier Management
  487. ;//
  488. ;////////////////////////////////////////////////////// 
  489.  
  490. ; 
  491. ; * Modifiers describe special characteristics of names
  492. ; * and properties.  Modifiers might be supported for
  493. ; * some names and not others.
  494. ; * 
  495. ; * Device Drivers should not rely on functionality
  496. ; * specified as a modifier.  These interfaces
  497. ; * are for use in writing Experts.
  498. ; 
  499.  
  500. ; 
  501. ; * Get and Set operators for entry modifiers
  502. ; 
  503.  
  504. ;
  505. ; extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers)
  506. ;
  507.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  508.         IMPORT_CFM_FUNCTION RegistryEntryGetMod
  509.     ENDIF
  510.  
  511. ;
  512. ; extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers)
  513. ;
  514.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  515.         IMPORT_CFM_FUNCTION RegistryEntrySetMod
  516.     ENDIF
  517.  
  518. ; 
  519. ; * Get and Set operators for property modifiers
  520. ; 
  521.  
  522. ;
  523. ; extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers)
  524. ;
  525.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  526.         IMPORT_CFM_FUNCTION RegistryPropertyGetMod
  527.     ENDIF
  528.  
  529. ;
  530. ; extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers)
  531. ;
  532.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  533.         IMPORT_CFM_FUNCTION RegistryPropertySetMod
  534.     ENDIF
  535.  
  536. ; 
  537. ; * Iterator operator for entry modifier search
  538. ; 
  539.  
  540. ;
  541. ; extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers)
  542. ;
  543.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  544.         IMPORT_CFM_FUNCTION RegistryEntryMod
  545.     ENDIF
  546.  
  547. ; 
  548. ; * Iterator operator for entries with matching 
  549. ; * property modifiers
  550. ; 
  551.  
  552. ;
  553. ; extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers)
  554. ;
  555.     IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  556.         IMPORT_CFM_FUNCTION RegistryEntryPropertyMod
  557.     ENDIF
  558.  
  559.  
  560.     ENDIF ; __NAMEREGISTRY__ 
  561.  
  562.